3D GFX

home *** CD-ROM | disk | FTP | other *** search

/ 3D GFX / 3D GFX.iso / amiutils / i_l / jacosub / documentation / overview.doc < prev next >

Wrap

Text File | 1995-12-31 | 29.9 KB | 664 lines

JACOsub: video titling software for professionals version 2.4 Timed Script Editor, Timer, and Player A Product from Unicorn Research Corporation This document provides an overview of the JACOsub software package (features, installation, compatibility, script conversion, and product support). Be sure to read the product support section concerning bug reports, if you don't read anything else. Other documentation files in this package are: JACOsub.doc - Information on operating the program. JScripts.doc - Detailed information on the JACOsub script format specification. ARexx.doc - Covers ARexx communications with JACOsub. QuickRef.doc - Quick reference for script commands and directives. FAQ - Some Frequently Asked Questions, with answers. Register.doc - Information about registering the software. CONTENTS OF THIS DOCUMENT ========================= 1. What is JACOsub? 2. Special features of JACOsub 3. System requirements 4. Installation a. General information b. Installation on SINGLE-DRIVE systems 5. Interactions with other software and hardware 6. Genlock support 7. ARexx support (see ARexx.doc) 8. JConvert script conversion utility 9. JACOsub script file format specification (see JScripts.doc) 10. Shareware registration / commercial licensing (see register.doc) 11. Legal disclaimer 12. Support, technical questions, suggestions, bug reports 13. KNOWN BUGS -- PLEASE HELP 1. WHAT IS JACOsub? ==================== JACOsub is a program designed for displaying timed sequences of titles and graphics over a video. Professional-quality output and flexibility have been the primary goals since the program's inception. It was originally written for the Japanese Animation Club or Orlando (JACO) to lay English subtitles over Japanese-language films and television shows. The program has spread and grown in popularity due to its extremely flexible script format, clean multi-buffered title transitions, and other features described in the next section. The development of JACOsub has been primarily user-driven. Most of the program's more interesting features exist because users suggested them. Because of the valuable input given by so many people, JACOsub has become an exceptionally powerful program while retaining its initial simplicity at the same time. 2. SPECIAL FEATURES OF JACOsub =============================== * Non-sequential events. Title time ranges may overlap. * Fully integrated text-based script editor. If needed, video titles may be positioned graphically with the mouse. * Handles all kinds of time units: SMPTE, 1/100 second units, etc. * Extremely flexible timing script file format, allowing comments, blank lines, text directives, and global configuration commands. Scripts can be as simple or as complex as you want. Scripts may even include other scripts, so you don't have to re-time parts that you use over and over again. * Complete script-based control over text position, margins, font, style, colors, palettes, backshadow, word-wrapping, and justification. You can even generate anti-aliased outlines and shadows on mono-color text. Text appearance can be controlled through line directives or with C-style escape code inside the subtitle text. * Real-time script timing procedure allows you to time your script in small sections, and in independent tracks. The program offers intelligent calculation of title end times and forced gaps, leaving you free to concentrate only on title start times during timing. * Display graphic images with the text. Time ranges for graphic images may overlap also. Graphics (IFF pictures or brushes) may be positioned anywhere on the screen. If you do not need to generate text over graphics, you can load IFF pictures independently of JACOsub's display. JACOsub supports AGA graphics! * Multi video buffering and page switching. Many titling programs create a display in a hidden buffer, then blit it to the visible foreground at the proper time. But the duration of a multi-bitplane blit can be up to 3 video frames. This can cause disconcerting "flashing" effects. Both TurboTitle and PJS's software have this problem. JACOsub has a better way: It uses video-page switching rather than blitting, to move displays to the foreground. Images appear instantaneously during the vertical CRT blank interval. Blitting is only used to copy data between up to five hidden video buffers, never on the visible display. * You can make time shift and drift adjustments "on the fly" while your script is playing. * ARexx support -- other programs can issue commands to JACOsub, and your JACOsub scripts can execute ARexx scripts while playing. You can even control JACOsub's editor through ARexx. * You can control the Digital Creations SuperGen genlock faders directly from your script! GVP and Video Toaster genlock fades may be controlled indirectly through ARexx scripts. * Robust compiler diagnostics for tracking down problems in your scripts. * Support for 3rd-party script formats: TurboTitle (.tts), Phoenix Japanimation Society (.pjs), generic (.tim), Panimator (.pan), Subtitle (.sub) and ZeroG (.zeg). The Jconvert utility is provided to convert all these formats to JACOsub (.js) format. JACOsub can read directly all but .pan, .sub, and .zeg scripts without prior conversion. Author: Alex Matulich 1515 Jefferson Davis Hwy #820 Arlington, VA 22202-3311 (703) 413-0215 email: matulich_a@SEAA.NAVSEA.NAVY.MIL Beta Testers: Fred A. Leggett III (JACO), Daric Kozlowski (JACO) Tom Perry (Phoenix Japanimation Society) Noel Gamboa (Operation X) Robert Lowrey (Central Anime) Roger Ang, Jacob Ellis, Dave Fleming, Mike Harlock, Tommy Hwang, Ed Sum Compiler: SAS Amiga C/C++ 6.51 Computer: Amiga 1000 (never say die!) with WorkBench 2.1 AmigaDOS 2.04 ROM hacked in, 2M FAST, 512K CHIP, 30MB C-Ltd HD 3. SYSTEM REQUIREMENTS ======================= JACOsub will run on any model Amiga computer, either PAL or NTSC. Recommended hardware requirements: * At least 1 megabyte RAM, preferably more than 1.5 megabytes * Two storage devices (2 floppy drives, hard disk and floppy, or RAM disk and single disk drive) Recommended software requirements: * AmigaDOS 2.0 or greater (program WILL run under 1.3; see next section for caveats concerning 1.3) * libs: dirrectory should contain asl.library or req.library (for file requesters) iffparse.library (for IFF file support; 1.3-compatible version exists) supergen.library and copinint.library (if you have a SuperGen genlock) The program will still run without these libraries. Additional hardware needed for video work: * Amiga-compatible genlock (for overlaying computer images onto video) * Source video device, preferably a laserdisc player * Videocassete recorder for making master recordings * Second video monitor is useful but not required. 4. INSTALLATION ================ a. General information ---------------------- After extracting the archive you should have the files in the list below. An "I" in the first column indicates that the file has an icon (.info file) associated with it. I README.1st Quick install and run instructions I CHANGES.TXT List of improvements and bug fixes I InstallFonts Installs JACOsub's fonts into fonts: I JACOsub The timing script compiler & player JACOsub.cfg Empty config file to replace older ones I jconvert Conversion utility for 3rd-party scripts proglogo.bbm Initial graphic that appears in the editor I documentation (subdirectory) I Overview.doc You're reading it now I JACOsub.doc Documentation on operating the software I JScripts.doc JACOsub Script file format specification I ARexx.doc ARexx communications documentation I Register.doc Shareware registration instructions I FAQ Frequently-Asked Questions, with answers fonts (subdirectory) JACOsub.font A few high-quality video titling fonts JACOsub (subdirectory) 18e 18-pixel height monochrome font for clock 29.4C 29-pixel international color outline font 32.4C 32-pixel international outline/shadow font 36.4C 36-pixel international outline/shadow font JACOsub_superhires.font Titling font for use in SUPERHIRES mode JACOsub_superhires (subdirectory) 36.4C SUPERHIRES color outline font rexx (subdirectory) abortplay.jsrx Demo of ABORTPLAY ARexx command begintime.jsrx Demo of BEGINTIME ARexx command loadscript.jsrx Demo of LOADSCRIPT ARexx command playsetup.jsrx Demo of PLAYSETUP ARexx command playstart.jsrx Demo of PLAYSTART ARexx command quit.jsrx Demo of QUIT ARexx command savescript.jsrx Demo of SAVESCRIPT Arexx command screentoback.jsrx Demo of SCREENTOBACK ARexx command screentofront.jsrx Demo of SCREENTOFRONT ARexx command etc... ...and various others described in ARexx.doc I scripts (subdirectory) I demo.js Demonstration script for JACOsub I idemo.js Secondary script included by demo.js I JACO.bbm Graphic logo; IFF brush used by demo.js All you need to do to install the software after you extract the archive, is copy the supplied fonts to your fonts: directory. To do this, simply double-click on the "InstallFonts" icon, or enter these commands from the JACOsub directory at a Shell prompt: copy fonts fonts: all ;copy the supplied fonts delete fonts all ;delete the fonts directory created by the ;archive extraction. THE JACOsub FONTS MUST BE IN YOUR FONTS: DIRECTORY PRIOR TO RUNNING THE PROGRAM FOR THE FIRST TIME. The fonts get updated and improved periodically, so you should always re-install them if CHANGES.TXT indicates that it is necessary. BE SURE YOUR SYSTEM CLOCK IS SET CORRECTLY BEFORE INSTALLING THE FONTS, because JACOsub checks the jacosub.font date to see if it's recent enough. If you have a SuperGen genlock, you need to make sure that your LIBS: directory contains supergen.library and copinit.library. If they are missing, you won't be able to control your SuperGen from JACOsub scripts. Before you run the program, you should be aware of some issues concerning different versions of AmigaDOS: AmigaDOS 1.2: You will not be able to run JACOsub with color fonts. If you boot up with a 1.3 disk using 1.2 Kickstart, you may have better luck. In any case, upgrade to 1.3 or 2.0 as soon as you can. Your libs: directory should contain req.library. JACOsub does not support AmigaDOS 1.2; if it works at all, it's purely an accident. AmigaDOS 1.3: You will need to load a Colortext driver prior to running JACOsub. A good Colortext driver by InterActive Softworks is supplied with Deluxe Paint IV or Calligrapher. If you don't load this driver, you will see only single-colored characters while JACOsub runs. >> DO NOT USE ColorTextWedge 1.2 (supplied with TurboTitle) -- it forces all text into JAM2 mode which chops up fonts having overlapping dropshadows (such as the supplied JACOsub font). Also, your libs: directory should contain req.library, though it's not required. >> Under 1.3, JACOsub's IFF capabilities will be unavailable to you unless you have a 1.3-compatible version of iffparse.library in your libs: directory. ARexx has a similar restriction under 1.3. AmigaDOS 2.0 users do not need any special driver -- it's built into 2.0. You don't need req.library, but your libs: directory should contain the AmigaDOS asl.library. It's a good idea to patch it with the reqtools.library patch utility if you have it. Under AmigaDOS 2.s, you will be unable to load files using AGA video modes. AmigaDOS 3.0 and above: Should behave the same as AmigaDOS 2.0, except that you can load IFF files that use AGA graphic modes. Now you're ready to begin. Just click twice on JACOsub's program icon, or type "run jacosub" from a Shell prompt. Refer to JACOsub.doc for more detailed information on operating the program. b. Installation on single-drive systems ---------------------------------------- This procedure requires some knowledge of the AmigaDOS Shell. If your computer's only storage device is a single floppy disk drive, you will need to create a minimal Workbench disk that will allow you to boot up your machine and run JACOsub on the same disk. The scripts directory contains a Shell script called MakeWB that will create a minimal Workbench disk for you. To make a minimal Workbench disk, first make a copy of your original Commodore-issue Workbench disk and boot up from it. Copy MakeWB to this disk, and execute it from a Shell prompt by typing this line: makewb df0: (assuming df0: is the name of your floppy drive; some Amigas use fd0:). The script will copy the necessary files to RAM: and then ask you to insert a formatted floppy disk in the drive. After you do this, it will copy the files needed for a minimal Workbench boot disk from RAM: to the blank disk. The new disk should be about 30% full. After you have made your boot disk, you should have enough space on it to copy the files in JACOsub's main directory to the root of your new disk, and JACOsub's fonts to the new disk's fonts: directory. You can save some additional space by deleting the documentation files. 5. INTERACTIONS WITH OTHER SOFTWARE AND HARDWARE ================================================= Beta Versions of AmigaDOS: Avoid. In particular, a beta version of AmigaDOS 2.1 has been known to result in strange "snow," or random flecks of color, appearing on the screen while JACOsub plays a script. Directory Opus 4.0: DO NOT use JACOsub with Directory Opus 4.0! This version of Directory Opus has some known problems that will cause you much grief if you try to run JACOsub with it. You should probably avoid directory utilities altogether when running JACOsub! EPU, PowerPacker, and other filesystem compression utilities: File compressors used to give JACOsub problems before version 1.9 if the compressor was set to report the compressed sizes of files, rather than the original, uncompressed size. This no longer matters; disk compressors should cause no trouble. Text editors: Some users have reported that certain text editors, when run in the background while JACOsub is running, will mess up time events. TxEd causes no problems at all. Other users have reported no problems with CED. In any case, it is probably a good idea to shut down unnecessary tasks before running ANY timing-critical application such as JACOsub. req.library: You should have either asl.library or req.library in your libs: directory. The program should still work fine without these, however. Warning: I have observed instances of req.library trashing memory location $00000078 (in the zero-page memory area) which is dangerous for AmigaDOS. If your computer crashes right before a file requester should appear, the fault is with req.library, not JACOsub. JACOsub will use asl.library if it can be found. reqtools.library: Highly recommended! The patch utility that comes with reqtools.library patches req.library, asl.library, and arp.library to use features in reqtools.library. It fixes the problem with req.library described above. Reqtools.library makes your Amiga (and JACOsub) significantly more pleasant to use. Genlocks: In general, be sure all video sources are off, and your genlock is not trying to gain a lock on anything, when you boot up your computer. Genlocks affect the Amiga's internal clocking, and can cause timing instabilities if you power everything up in the wrong order. GVP genlocks seem to be especially fussy about how they are brought online. GVP users: load IFF files with JACOsub at your own risk. There is an incompatibility between the GVP and the AmigaDOS IFF loader routines. Contact Great Valley Products for more information and updated software. SuperGen users should have at least version 2.0 of the supergen.library and copinit.library. See the GENLOCK SUPPORT section below for details. GVP 1230+ Turbo Series II accelerator: If you have problems with mysterious lockups, or random pixels appearing on the screen, try re-seating the chips. If that doesn't work, then disable the data cache using the CPU NODATACACHE AmigaDOS command. 6. GENLOCK SUPPORT =================== SuperGen (Digital Creations) -------- JACOsub allows your scripts to control the faders on a SuperGen genlock. You need to have supergen.library and copinit.library in your LIBS: directory to take advantage of this feature. These libraries are available from the libs directory of your Digital Creations SuperGen software disk. SUPERGEN.LIBRARY VERSIONS LESS THAN 2.0 WILL NOT WORK WITH JACOsub. If your SuperGen library is too old, your fades will results in jittery dissolves. Update your SuperGen library as soon as possible. JACOsub will not assume control over the SuperGen until it must execute a fader command. From that point on, the genlock will be under software control until the script play terminates, and then control will be returned to manual mode. Warning! DO NOT BOOT UP YOUR AMIGA WITH A SIGNAL PRESENT ON THE SUPERGEN'S VIDEO INPUT!! Doing so will adversly affect the Amiga's system clock, which will cause your scripts to run erratically or much too fast! See the G directive in the Script Format Specification documentation JScripts.doc, for information on controlling the SuperGen. Other genlocks will be supported as software and documentation becomes available to the author. GVP Genlock (Great Valley Products) ----------- Dissolves with the GVP G-Lock must be controlled through ARexx. JACOsub will look for the ARexx script "gvpfade.jsrx" in the current directory, a "rexx" subdirectory under the current directory, and in REXX:, and copy the script to ram:glfade.jsrx for faster execution. This script is currently not provided. See the file ARexx.doc for specifications of this script. If you create such a script, please send it to us! If you have a GVP Genlock, PLAY SCRIPTS THAT LOAD IFF GRAPHICS AT YOUR OWN RISK! Your Amiga WILL VERY LIKELY crash! Great Valley Products says that the normal AmigaDOS IFF loading routines cause problems when the GVP is in operation. Contact GVP for updated software. Setting GENLOCK to GVP in your JACOsub.cfg file will cause a compile-time warning to be issued if a script attempts to load an IFF file. Video Toaster (NewTek) ------------- The first paragraph under "GVP Genlock) above applies to the Video Toaster also, only the script should be named "toasterfade.jsrx." General Information ------------------- Warning! The genlock may sometimes show things that do not appear on the RGB display. Some examples we discovered: A vertical line appears on the right edge of genlocked display, but not on the RGB display. The solution is to make sure the horizontal screen size is a multiple of 32, such as 640, 672, or 704. Digital Creations tells us that this line won't appear on your videotape, but we suspect they're talking about a different phenomenon. Little pieces of characters from the left side of the screen appear on the right edge. This happens when a character's kern setting causes the left edge of the screen to clip off a pixel or two, as in the 'W' and 't' of the 36-pixel JACOsub font. You can see this when you run the demo script after changing the left margin to 0% by inserting the line #HL0 at the top of the script. Solution: Use the HL1 directive instead of HL0, to provide a few pixels of margin space. This will keep kerned characters from going past the left edge of the display. 7. AREXX SUPPORT ================= If you have ARexx, JACOsub will open an ARexx port called 'JACOsub'. You can use a different program (such as SCALA for example) to issue a number of commands to JACOsub, and you can have JACOsub execute ARexx scripts while a JACOsub script is playing. For more information, see the file ARexx.doc. 8. JCONVERT SCRIPT CONVERSION UTILITY ====================================== Although JACOsub can read directly TurboTitle and Phoenix scripts, they won't be able to use many of JACOsub's advanced features. If you need text with non-sequential, overlapping time ranges, or if you need to control the positioning or attributes of the text, or if you want to play a Panimator script with JACOsub, you must convert the script to the JACOsub script format. You don't *have* to convert .pjs or .tts scripts to JACOsub format if you need only to adjust text style or color (green italics, etc.). For these operations, you can insert style and color codes directly into your text, and still retain compatibility with your other timing software. Your other software won't use these codes (they'll get displayed on the screen instead). See the Script File Format Specification documentation JScripts.doc for descriptions of the possible codes that you can use. If you need to convert to JACOsub, it's very simple. The Shell command is jconvert [-v[erbose]] scriptname1.ext [scriptname2.ext] ... where .ext can be: .tts (TurboTitle) .pjs (Phoenix Japanimation Society) .tim (Generic) .pan (Panimator) .sub (Subtitle) .zeg (ZeroG) The optional -v or -verbose switch causes jconvert to echo its output to the screen as it writes the new file. To run jconvert from Workbench, you can click on its icon twice. A file requester will appear, allowing you to select a file to convert. If you have SCRIPTPATH specified in JACOsub.cfg, jconvert will use this as the starting directory for the file requester. Or, if you need to convert multiple scripts, you may multiply select your script icons (clicking while holding down the SHIFT key) ending with a double-click on the jconvert icon. Jconvert will read in the script, and write out a new script file called scriptname.js which will be in JACOsub format. Then you can modify scriptname.js to take advantage of JACOsub's advanced features. Source code for jconvert is available separately. It should work for any computer or operating system. If you need it, write to the author, check your local BBS, or call Anime Central BBS (see information at the end of this document). NOTICE: We recommend that you let JACOsub try to read your script PRIOR to converting it with jconvert, because JACOsub can inform you of potential problems with your script, but jconvert cannot. Jconvert does not analyze your scripts; it simply converts them blindly. The only exception is when converting TurboTitle scripts, jconvert will correct overlapping time ranges by shortening the previous line's end time to be equal to the current line's start time. 9. JACOsub SCRIPT FILE FORMAT SPECIFICATION ============================================ See the textfile JScripts.doc for a complete description of the JACOsub script file format. About those 3rd-party file formats ---------------------------------- Robert Jenks, the author of TurboTitle, made an excellent suggestion in his documentation, that the TurboTitle format should be adopted as a standard for future software. JACOsub is compatible with TurboTitle files, but the TurboTitle format was just not flexible enough for our needs. We needed to use SMPTE time units, we needed to control color, style, and positioning of text, we needed to insert comments in the script and inside the text, and we needed no restrictions on how time events were sequenced. (We also needed something that displayed text faster and more cleanly, but that had nothing to do with the file format.) The preceding paragraph is not meant to be critical of Mr. Jenks' work. TurboTitle was a fine program for its time, and it served to provide some inspirational influence for JACOsub. We feel that the JACOsub script file format is the most flexible yet developed. Scripts can be as simple as TurboTitle scripts, containing only timing numbers and text, or you can go all out with global commands and complex formatting directives. We will follow the example of TurboTitle's author, and ask that the JACOsub format be adopted as a standard for future titling software products. The format is flexible enough to evolve and grow, so if you have suggestions for improvements or changes, please let us know. And especially, if you want JACOsub to support another file format, tell us the specifications and we'll try to work it into either the program itself or the jconvert utility. 10. SHAREWARE REGISTRATION / COMMERCIAL LICENSING ================================================== Please refer to the file register.doc. 11. LEGAL DISCLAIMER ===================== (Shamelessly adapted from Haventree's EasyFlow documentation) We don't claim JACOsub is good for anything -- if you think it is, great, but it's up to you to decide. If JACOsub doesn't work: tough. If you lose a million because JACOsub messes up, it's you that's out the million, not us. If you don't like this disclaimer: tough. We reserve the right to do the absolute minimum provided by law, up to and including nothing! This is basically the same disclaimer that comes with all other software packages, but ours is in plain English and theirs is in Legalese. Additional disclaimer: The author will attempt to update the software as needed, but is not obligated to do so. 12. SUPPORT, TECHNICAL QUESTIONS, SUGGESTIONS, BUG REPORTS =========================================================== You can contact the author, Alex Matulich, at the address in section 2 of this file. Alex may be reached via email, using these addresses: Internet: matulich_a@SEAA.NAVSEA.NAVY.MIL alex@bilver.oau.org (should automatically forward) Alex.Matulich@animece.oau.org (last resort) Fidonet: 1:363/137, name "Alex Matulich" (last resort) Support BBS: Anime Central 407-645-2241, N-8-1, 28,800 maximum baud Fidonet address 1:363/137. The latest version of JACOsub, plus timed scripts contributed by JACOsub users, are in the JACOsub Support file area. Please do not ask questions of the Sysop regarding JACOsub. Instead please direct all questions to Alex Matulich. Email server: Anime Central BBS has an email server with which you may request the latest version of JACOsub, scripts, and Anime- related material to be sent to you through email. To get started, simply send email to ftpmail@animece.oau.org. In the body of your message put this single line: send allfiles.lzh This is a complete listing of files on Anime Central. The archive will be sent to you in uuencoded format, so you will require a uudecode utility to convert it to usable form. You will also need LZ or LHA to extract the contents of .lzh or .lha archives. IMPORTANT: PLEASE LIMIT YOUR FTPMAIL REQUESTS TO LESS THAN ----------> 500 K PER DAY. Abusing this service will cause it to disappear forever, for everyone. JACOsub software and scripts are in the JACOsub file area. New versions of JACOsub will always have a file name of the form jcosub##.lzh, where ## is the version number; for example, version 2.4 would be jcosub24.lzh. IMPORTANT: WHEN SUBMITTING A BUG REPORT, BE SURE THE PROBLEM IS REPEATABLE AND SPECIFY THE CONDITIONS UNDER WHICH THE PROBLEM OCCURRED. Too many people report problems like "I got an error message when I tried to play my script" with no other information. This kind of report helps nobody! What version of JACOsub? What version of AmigaDOS? What kind of computer? What were you doing prior to noticing the problem? Can you reproduce it and isolate it enough for ME to be able to do the same? If you encounter a problem, try to isolate it. If the problem is being caused by something in your script, send the author a small sample script with your bug report that demonstrates the problem. Try running the program on another machine -- if it runs fine on another machine, try to determine what's different about your setup that's causing the trouble. And try to describe the bug as completely as possible in your report. 13. KNOWN BUGS -- PLEASE HELP ============================== From time to time a problem comes up that completely mystifies me. The purpose of this section is to list problems reported by users which I cannot reproduce. If you find a way to reproduce them reliably, PLEASE let me know (my addresses are at the end of section 2 of this document). Please provide as complete a description as possible, as described in the previous section. 1. When attempting to play a script, sometimes the following error message appears: "Unable to create temporary ... RastPort for font outlines or shadows." This messge can appear even if the computer has sufficient video memory. The only known solutions are to re-start JACOsub, or re-boot, and try again. 2. I have an isolated report of titles flashing up on the screen only momentarily, regardless of start and stop times, when trying to play a script converted from TurboTitle, under AmigaDOS 1.3 on an Amiga 500, when the timer is set to "Event" ("Polled" works fine). 3. Enforcer hits -- Please inform me of any you encounter. If you're still reading this far, thank you for using JACOsub. End of Overview.doc.